docs-audit: state where every emitted anchor came from - #13738

Fixes #12824

Implements option C of the maintainer's ruling of 2026-08-31 (verbatim 「同意」), and only C: every row the docs-drift advisory emits now states where its anchor came from — the member and the declaration enclosing it — so a reader can judge the row instead of guessing.

before:  organizationId (symbol)
after:   organizationId (symbol, a field of interface MetaOverlayCacheKey)
after:   userActions    (symbol, a field of const object ObjectSchemaBase)

Those last two are the same syntactic form — name: inside an object or interface — and that is the whole finding. One is a field of an internal cache struct that lands 10 pages documenting an unrelated organizationId; the other is the canonical authorable key whose row is the best this tool produces. The card's three disproven discriminators (syntactic form, declaring package, property name against the authorable registry) all fail to separate them. The declaring container separates them, and no row printed it before.

Scope — what this deliberately is not

• ⛔ No recall change, no threshold moved. No anchor is filtered, dropped or reweighted. OVERBROAD_ANCHOR_SHARE, MAX_ROUTES_PER_SYMBOL and documentableDeclarationsAt's selection are byte-identical.
• ⛔ Not option B. Nothing discriminates on the new field. B is ruled down on two rounds of measurement, and this change is its deliberate opposite: publish the distinction, act on none of it.
• D stays on spec: emit the TS-declaration-name → spec-type-name mapping from gen:schema (unblocks docs-audit option D, #12824) #13712 / docs-audit: qualify data-property anchors by declaring container against authorable-surface (option D on #12824) #13713. Container-qualified discrimination needs the TS-name to spec-name mapping this does not have. Not addressed here; those cards remain open.

Proof that the anchor set is unchanged — measured, not asserted

Both arms of affected-docs.mjs (origin/main and this branch) were run against the same tree at the same commit over 100 consecutive main commits touching packages/, comparing the full --json output:

Compared per commit: the anchor set as kind + token; the docs list; and the entire JSON document once the two additive fields (anchors[].from, and the clause appended inside each detail[].via string) are removed. All three byte-identical on every commit. Harness and per-commit records are in the dev report on #12824.

The same property is pinned in --self-test rather than left to this one measurement: the provenance key set is asserted to be exactly the anchor set, in both directions — never a superset (a name nothing minted) and never a subset (an anchor with no clause). A future change cannot start deciding with from without going red.

The ruling's own example, end to end

Driven through the real pipeline by committing a one-line widening at each declaration site and running both arms at HEAD^:

content/docs/data-modeling/objects.mdx — the true positive option B drops — is present in both arms, unchanged.

Every anchor kind names its origin

symbol is the card's subject, but the card also records the bridge amplification it feeds (publishItem (sdk) and /:type/:name/publish (route) on a diff touching no state machine), and that is only judgeable when the row names the hop it rode. From a real run on this tree:

sdk    meta.getView                    the route ledger binds it to GET /api/v1/ui/view/:object/:type
route  /view/:object/:type             bridged from symbol enforceEnvironmentOwnership — its registrar handler names it
route  /api/v1/ui/view/:object/:type   a path literal in RestServer
symbol computeExecCtx                  a method of class RestServer

Measured cost

The advisory comment gets longer, which the ruling accepted implicitly (C "does not reduce the row count"). Quantified on the worst run in the 100-commit population: the rendered row block grows 1265 → 2312 bytes (x1.8) at the 15-row display cap. That worst case is command anchors, whose clause was first drafted as the CLI command id ID, read off FILE — a restatement of the token — and is now just read off FILE, which took the worst single row from 2201 to 1549 chars. Median row is 76 chars, p90 222.

⛔ The display-cut problem itself is not addressed here and survives, exactly as the card says of option C.

Verification

• node scripts/docs-audit/affected-docs.mjs --self-test — 503 cases pass (487 before; +16 pins for the provenance derivation, the member-form classifier including its degraded answer, and the key-set invariant).
• node scripts/docs-audit/check-affected-docs.mjs — exit 0 (self-test + --bridge-coverage; discovered population unchanged).
• node scripts/docs-audit/check-drift-comment.mjs — 56 cases pass across 5 fixture diffs. This runs the workflow's real comment script against real mapper output, so it is also the check that the added clause does not break the renderer.
• pnpm lint (repo-wide, eslint . --no-inline-config) — exit 0.
• Derived gate family (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack), all exit 0: check:nul-bytes, check:docs-audit-scope, check:watch-hint-literal, check:agent-test-spelling, check:entry-guard, check:parse-guard, check:cli-command-ids, check:pnpm-filter-targets, check:bash32-floor, check:pm-governed-merges, check:cross-package-test-inputs, check-self-test-wired, check-ci-filter-parity, check-shard-attestation.
• check-test-completeness.mjs — NOT MEASURED (PREREQUISITE NOT MET, exit 3): it grades a saved turbo run test log and the family names it with no argument. Not a red.
• Reverse verification, on the committed tree, mutation and restore both proven on disk: inverting memberFormOn's verdict reds 8 pins; withholding the provenance write reds the 4 key-set invariant pins. Restored blob 56b1f118… matches HEAD and git diff HEAD is empty in both cases.

All of the above ran at 8087897a7, the branch head.

No changeset: this edits a CI-internal tooling script and its README and publishes nothing from any package — the skip-changeset case the workflow prescribes.

Generated by Claude Code